W08-2. Service 와 Gateway API - 실습 가이드
8주차 실습: Service 로 묶고, Gateway API 로 도메인 주소 공개하기
- ClusterIP Service 를 만들고, 요청이 Pod 3개로 나눠 가는 것을 확인한다.
- NodePort / LoadBalancer 를 만들어 보고, Docker Desktop 에서의 동작 차이를 확인한다.
- Envoy Gateway 를 설치하고
http://guestbook.localhost로 방명록을 공개한다. - 도메인에 따라 다른 앱으로 보내는 라우팅을 해 본다.
- Kubernetes running, 컨텍스트
docker-desktop - 작업 폴더: macOS
cd ~/docker-study/k8s/ Windowscd "$HOME\docker-study\k8s" - 7주차
deployment.yaml이 v2, replicas 3 인 상태로 있어야 합니다. 지웠다면 다시 적용합니다.kubectl apply -f deployment.yaml kubectl get pods - 브라우저: Chrome 또는 Edge 권장 (
*.localhost주소 사용)
| 실습 | 내용 | 시간 |
|---|---|---|
| 1 | ClusterIP Service 와 로드밸런싱 | 8분 |
| 2 | Service 는 Pod 를 따라간다 | 4분 |
| 3 | NodePort 와 LoadBalancer | 7분 |
| 4 | Envoy Gateway 설치 | 5분 |
| 5 | Gateway + HTTPRoute 로 공개 | 8분 |
| 6 | 도메인별 라우팅 | 6분 |
| 7 | 메모리 저장의 한계 체험 | 4분 |
| 8 | 정리 | 3분 |
실습 1. ClusterIP Service 와 로드밸런싱
1-1. service.yaml
VS Code 로 k8s 폴더에 service.yaml 을 만듭니다.
apiVersion: v1
kind: Service
metadata:
name: guestbook
spec:
type: ClusterIP
selector:
app: guestbook
ports:
- port: 80
targetPort: 8000
kubectl apply -f service.yaml
kubectl get service guestbook
출력 예시:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
guestbook ClusterIP 10.96.134.220 <none> 80/TCP 0s
1-2. Service 가 찾은 Pod 목록 (EndpointSlice)
kubectl get endpointslices -l kubernetes.io/service-name=guestbook
kubectl get pods -o wide
출력 예시: ENDPOINTS 의 IP 3개가 Pod 3개의 IP 와 같습니다.
NAME ADDRESSTYPE PORTS ENDPOINTS AGE
guestbook-jcbh9 IPv4 8000 10.244.0.32,10.244.0.33,10.244.0.34 0s
1-3. 클러스터 안에서 접속해 보기
ClusterIP 는 클러스터 안에서만 접속됩니다. 테스트용 Pod 를 하나 띄워 두고 그 안에서 요청을 보냅니다.
kubectl run study-client --image=alpine:3.24 -- sleep 3600
kubectl wait --for=condition=Ready pod/study-client --timeout=60s
같은 주소(http://guestbook)로 6번 요청합니다.
kubectl exec study-client -- sh -c "for i in 1 2 3 4 5 6; do wget -qO- http://guestbook/healthz; echo; done"
출력 예시: hostname 이 여러 Pod 로 바뀌어 나옵니다.
{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-7fqvb","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-7fqvb","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-8kqk4","status":"ok","version":"v2"}
5주차 Compose 에서 --scale web=3 이 포트 충돌로 실패했던 것을, Kubernetes 는 Service 하나로 해결합니다. 순서는 무작위라 사람마다 다르게 나옵니다.
1-4. 이름이 IP 로 바뀌는 것 확인 (DNS)
kubectl exec study-client -- nslookup guestbook.default.svc.cluster.local
출력 예시 (끝부분): Service 의 CLUSTER-IP 가 나옵니다.
Name: guestbook.default.svc.cluster.local
Address: 10.96.134.220
짧은 이름(
nslookup guestbook)으로 하면 alpine 의nslookup이 여러 도메인을 차례로 시도하다가NXDOMAIN을 함께 출력하기도 합니다. 위처럼 전체 이름으로 확인하세요.wget http://guestbook처럼 실제로 접속할 때는 짧은 이름으로 잘 됩니다.
실습 2. Service 는 Pod 를 따라간다
kubectl scale deployment guestbook --replicas=5
kubectl get endpointslices -l kubernetes.io/service-name=guestbook
출력 예시: 5개로 늘어난 Pod 가 자동으로 목록에 들어갑니다.
NAME ADDRESSTYPE PORTS ENDPOINTS AGE
guestbook-jcbh9 IPv4 8000 10.244.0.32,10.244.0.33,10.244.0.34 + 2 more... 3m
다시 3개로 돌립니다(파일 기준).
kubectl apply -f deployment.yaml
kubectl get endpointslices -l kubernetes.io/service-name=guestbook
Service 설정은 한 번도 고치지 않았습니다. 라벨(
app=guestbook)만 맞으면 Pod 가 늘든 줄든, 롤링 업데이트로 바뀌든 Service 가 알아서 따라갑니다.
실습 3. NodePort 와 LoadBalancer
3-1. NodePort
service-nodeport.yaml
apiVersion: v1
kind: Service
metadata:
name: guestbook-np
spec:
type: NodePort
selector:
app: guestbook
ports:
- port: 80
targetPort: 8000
nodePort: 30080
kubectl apply -f service-nodeport.yaml
kubectl get service guestbook-np
출력 예시:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
guestbook-np NodePort 10.96.249.217 <none> 80:30080/TCP 5s
브라우저에서 http://localhost:30080 을 열어 보세요. → 열리지 않습니다.
NodePort 는 노드(서버)의 포트를 엽니다. Docker Desktop(kind)의 노드는 노트북 안의 컨테이너라서, 노드에 열린 30080 이 노트북의 30080 으로 연결되지 않습니다.
실제 서버로 만든 클러스터라면 서버IP:30080 으로 접속됩니다.
노드 IP 를 확인하고, 클러스터 안(테스트 Pod)에서 노드 IP:30080 으로 접속해 봅니다.
kubectl get nodes -o wide
INTERNAL-IP 열의 주소 중 하나(예: 172.23.0.4)를 아래에 넣습니다.
kubectl exec study-client -- wget -qO- http://172.23.0.4:30080/healthz
출력 예시:
{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
노드의 30080 으로 들어온 요청이 Service 를 거쳐 Pod 로 갔습니다. 어느 노드의 IP 로 보내도 똑같이 동작합니다.
3-2. LoadBalancer
service-lb.yaml
apiVersion: v1
kind: Service
metadata:
name: guestbook-lb
spec:
type: LoadBalancer
selector:
app: guestbook
ports:
- port: 8090
targetPort: 8000
kubectl apply -f service-lb.yaml
kubectl get service guestbook-lb
출력 예시: 몇 초 뒤 EXTERNAL-IP 가 채워집니다. 처음에는 <pending> 일 수 있습니다.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
guestbook-lb LoadBalancer 10.96.198.149 172.23.0.5 8090:32164/TCP 16s
브라우저에서 http://localhost:8090 → 방명록 v2 가 보입니다.
172.23.0.5는 Docker Desktop 내부 네트워크의 주소라 노트북 브라우저에서는 접속되지 않습니다.- 대신 Docker Desktop 이 LoadBalancer 를
localhost:포트로 연결해 줍니다(실제 확인). - 클라우드(EKS, NKS 등)에서는 EXTERNAL-IP 자리에 클라우드 로드밸런서의 진짜 공인 주소가 붙습니다.
- PORT(S) 의
8090:32164처럼, LoadBalancer 는 NodePort 도 자동으로 엽니다(타입의 포함 관계).
실습용 두 Service 는 지웁니다.
kubectl delete -f service-nodeport.yaml -f service-lb.yaml
실습 4. Envoy Gateway 설치
Gateway API 의 구현체인 Envoy Gateway 를 설치합니다. Gateway API 의 규격 정의(CRD)도 함께 설치됩니다.
kubectl apply --server-side -f https://github.com/envoyproxy/gateway/releases/download/v1.9.2/install.yaml
출력 예시 (끝부분): 많은 줄이 serverside-applied 로 나옵니다.
...
job.batch/eg-gateway-helm-certgen serverside-applied
mutatingwebhookconfiguration.admissionregistration.k8s.io/envoy-gateway-topology-injector.envoy-gateway-system serverside-applied
준비될 때까지 기다립니다(처음에는 이미지를 받느라 1~2분 걸릴 수 있음).
kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
kubectl get pods -n envoy-gateway-system
출력 예시:
deployment.apps/envoy-gateway condition met
NAME READY STATUS RESTARTS AGE
eg-gateway-helm-certgen-w85qh 0/1 Completed 0 15s
envoy-gateway-6579bbfdf-q8xhd 1/1 Running 0 15s
--server-side 는 꼭 붙이세요설치 파일이 매우 커서, 이 옵션 없이 적용하면 실제로 이런 에러가 납니다(확인함).
... "httproutes.gateway.networking.k8s.io" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes
실습 5. Gateway + HTTPRoute 로 공개
5-1. gateway.yaml: 시공사(GatewayClass)와 정문(Gateway)
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: eg
spec:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: study-gateway
spec:
gatewayClassName: eg
listeners:
- name: http
protocol: HTTP
port: 80
---는 한 파일에 YAML 문서 여러 개를 넣을 때 쓰는 구분선입니다.
kubectl apply -f gateway.yaml
kubectl wait --timeout=3m gateway/study-gateway --for=condition=Programmed
kubectl get gatewayclass
kubectl get gateway
출력 예시:
gateway.gateway.networking.k8s.io/study-gateway condition met
NAME CONTROLLER ACCEPTED AGE
eg gateway.envoyproxy.io/gatewayclass-controller True 18s
NAME CLASS ADDRESS PROGRAMMED AGE
study-gateway eg 172.23.0.6 True 18s
Gateway 를 만들자 Envoy Gateway 가 Envoy 프록시 Pod 와 이를 외부에 여는 LoadBalancer Service 를 자동으로 만들었습니다.
kubectl get pods,services -n envoy-gateway-system
envoy-default-study-gateway-... 이름의 Pod 와 LoadBalancer 타입 Service(포트 80)가 보입니다. 실습 3-2 에서 본 것처럼 Docker Desktop 이 이것을 localhost:80 으로 연결합니다.
5-2. httproute.yaml: 안내표
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: guestbook
spec:
parentRefs:
- name: study-gateway
hostnames:
- "guestbook.localhost"
rules:
- backendRefs:
- name: guestbook
port: 80
| 부분 | 의미 |
|---|---|
parentRefs |
어느 정문(Gateway) 에 붙일지 |
hostnames |
어떤 도메인으로 들어온 요청인지 |
backendRefs |
어느 Service 의 몇 번 포트로 보낼지 (실습 1의 guestbook:80) |
kubectl apply -f httproute.yaml
kubectl get httproute
출력 예시:
NAME HOSTNAMES AGE
guestbook ["guestbook.localhost"] 5s
5-3. 브라우저로 접속
브라우저에서 http://guestbook.localhost 를 엽니다. → 방명록 v2 🎉
명령어로도 확인할 수 있습니다.
macOS:
curl http://guestbook.localhost/healthz
Windows (PowerShell): curl 이 아니라 curl.exe 로 칩니다.
curl.exe http://guestbook.localhost/healthz
출력 예시:
{"hostname":"guestbook-5f994cddb4-8kqk4","status":"ok","version":"v2"}
브라우저 → guestbook.localhost:80 → Gateway(Envoy) → HTTPRoute 규칙 → Service guestbook → Pod 3개 중 하나
- Safari 등 일부 브라우저는
*.localhost를 처리하지 못할 수 있습니다. Chrome / Edge 를 쓰세요. - Windows PowerShell 의
curl은Invoke-WebRequest의 별칭이라*.localhost를 찾지 못합니다(The remote name could not be resolved).curl.exe로 치세요. - 노트북의 80번 포트를 다른 프로그램(로컬 웹 서버 등)이 쓰고 있으면 연결되지 않습니다.
실습 6. 도메인별 라우팅
정문 하나로 두 번째 앱도 공개해 봅니다. nginx 를 hello 라는 이름으로 띄웁니다.
kubectl create deployment hello --image=nginx:1.30-alpine
kubectl expose deployment hello --port=80
kubectl rollout status deployment/hello
kubectl create deployment,kubectl expose는 Deployment 와 Service 를 명령으로 빠르게 만드는 방법입니다(테스트용).
httproute-hello.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: hello
spec:
parentRefs:
- name: study-gateway
hostnames:
- "hello.localhost"
rules:
- backendRefs:
- name: hello
port: 80
kubectl apply -f httproute-hello.yaml
kubectl get httproute
출력 예시:
NAME HOSTNAMES AGE
guestbook ["guestbook.localhost"] 2m
hello ["hello.localhost"] 4s
| 브라우저 주소 | 결과 |
|---|---|
| http://guestbook.localhost | 방명록 |
| http://hello.localhost | Welcome to nginx! |
| http://nothing.localhost | 404 (안내표에 없는 도메인) |
외부로 열린 곳은 Gateway 의 80번 하나뿐인데, 도메인을 보고 다른 앱으로 나눠 보냈습니다. 앱마다 LoadBalancer(외부 IP, 비용)를 만들 필요가 없습니다.
실습 7. 메모리 저장의 한계 체험
http://guestbook.localhost 에서 글을 하나 남기고, 새로고침을 여러 번 해 보세요. HOSTNAME 과 글 목록을 같이 보세요.
관찰 예시 (실제로 확인한 결과): 응답한 Pod 끝 5글자 : 보이는 글 개수
8kqk4:1 8kqk4:1 8kqk4:1 8kqk4:1 8kqk4:1 8kqk4:1 lftb5:0 7fqvb:0 8kqk4:1
방명록은 지금 메모리 저장 모드입니다. 글은 글을 받은 Pod 의 메모리에만 있고, 다른 Pod 에는 없습니다. Service 가 요청을 여러 Pod 로 나눠 보내니 어느 Pod 가 응답하느냐에 따라 결과가 달라집니다.
👉 해결: 모든 Pod 가 같은 DB 를 보게 하면 됩니다. 다음 주에 PostgreSQL 을 Kubernetes 에 올리고 방명록을 연결합니다.
(새로고침이 같은 Pod 로만 가서 차이가 안 보이면, 브라우저를 닫았다 열거나 다른 브라우저로 열어 보세요. 연결을 재사용하면 같은 Pod 로 가기 쉽습니다.)
실습 8. 정리
테스트용 Pod 와 hello 앱은 지웁니다.
kubectl delete pod study-client
kubectl delete -f httproute-hello.yaml
kubectl delete service hello
kubectl delete deployment hello
- Envoy Gateway (
envoy-gateway-systemNamespace) gateway.yaml의 GatewayClass / Gatewayhttproute.yaml,service.yaml,deployment.yaml
확인: kubectl get gateway,httproute,service,deployment
자주 나는 문제와 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| Service 의 ENDPOINTS 가 비어 있음 | selector 의 라벨이 Pod 라벨과 다름 |
kubectl get pods --show-labels 로 비교 |
wget: can't connect to remote host ... Connection refused |
targetPort 가 틀림 (예: 80 으로 씀) |
방명록은 8000 |
wget: bad address 'guestbook' |
Service 이름 오타, 또는 다른 Namespace | kubectl get svc 로 이름 확인 |
localhost:30080 이 안 열림 |
Docker Desktop(kind)의 정상 동작 | 실습 3-1 참고 (LoadBalancer 나 Gateway 사용) |
LoadBalancer 의 EXTERNAL-IP 가 계속 <pending> |
클러스터가 막 생성됨, 또는 kubeadm 방식 | 잠시 기다리기. Docker Desktop 에서 kind 방식인지 확인 |
metadata.annotations: Too long: may not be more than 262144 bytes (설치 중) |
--server-side 없이 apply |
--server-side 붙여서 다시 |
Gateway 의 PROGRAMMED 가 False |
Envoy Gateway 가 아직 준비 중 | kubectl get pods -n envoy-gateway-system 확인 후 기다리기 |
guestbook.localhost 가 안 열림 |
브라우저가 *.localhost 미지원, 80 포트 사용 중, HTTPRoute 미적용 |
Chrome/Edge 사용, kubectl get httproute 확인, curl.exe -H "Host: guestbook.localhost" http://localhost/ 로 테스트 |
오늘 쓴 명령어 정리
| 명령어 | 하는 일 |
|---|---|
kubectl apply -f service.yaml / kubectl get service |
Service 만들기 / 목록 |
kubectl get endpointslices -l kubernetes.io/service-name=이름 |
Service 가 찾은 Pod 목록 |
kubectl run study-client --image=alpine:3.24 -- sleep 3600 |
테스트용 Pod |
kubectl exec study-client -- wget -qO- http://이름/경로 |
클러스터 안에서 접속 테스트 |
kubectl exec study-client -- nslookup 이름.default.svc.cluster.local |
DNS 확인 |
kubectl apply --server-side -f <URL> |
큰 설치 파일 적용 |
kubectl wait --for=condition=... 대상 |
준비될 때까지 기다리기 |
kubectl get gatewayclass / gateway / httproute |
Gateway API 오브젝트 확인 |
kubectl create deployment 이름 --image=... / kubectl expose deployment 이름 --port=80 |
빠르게 만들기 (테스트용) |
복습 과제
확인 퀴즈
- Pod 의 IP 로 직접 접속하지 않고 Service 를 쓰는 이유는?
- Service 는 어떤 Pod 로 트래픽을 보낼지 어떻게 정하나요?
port: 80,targetPort: 8000은 각각 무엇의 포트인가요?- ClusterIP, NodePort, LoadBalancer 의 차이는?
- Ingress-NGINX 는 어떻게 되었고, 새로 설계할 때는 무엇을 쓰나요?
- Gateway API 의 GatewayClass, Gateway, HTTPRoute 는 각각 무슨 역할인가요?
- 실습 7에서 글이 보였다 안 보였다 한 이유와 해결 방법은?
- Pod 의 IP 는 다시 만들어질 때마다 바뀌고, Pod 가 여러 개라서 어디로 보낼지 정해야 하기 때문입니다. Service 는 고정된 이름과 IP 를 주고 요청을 나눠 보냅니다.
selector의 라벨과 일치하는 Pod 를 찾아 EndpointSlice 목록을 자동으로 유지합니다.port는 Service 가 받는 포트,targetPort는 Pod(컨테이너) 가 실제로 듣는 포트입니다.- ClusterIP 는 클러스터 안에서만, NodePort 는 모든 노드의 포트(30000~32767) 로 바깥에서도, LoadBalancer 는 클라우드 로드밸런서(외부 주소) 로 접속하게 합니다. 위 타입이 아래 타입의 기능을 포함합니다.
- 2026년 3월 지원이 종료되어 보안 패치가 나오지 않습니다. 새로 설계할 때는 후속 표준인 Gateway API 를 씁니다(Ingress API 자체는 아직 있음).
- GatewayClass 는 어떤 구현체를 쓸지, Gateway 는 실제 입구(포트·프로토콜), HTTPRoute 는 어떤 도메인·경로를 어느 Service 로 보낼지 정합니다.
- 메모리 저장 모드라 글이 글을 받은 Pod 에만 있었고, Service 가 요청을 여러 Pod 로 나눠 보냈기 때문입니다. 모든 Pod 가 같은 DB 를 쓰게 하면 해결됩니다(9주차).
도전 과제 (선택)
httproute.yaml의rules에 경로 조건을 넣어,http://guestbook.localhost/healthz만 받게 바꿔 보세요. 다른 경로는 어떻게 되나요?
확인 후에는 원래rules: - matches: - path: type: PathPrefix value: /healthz backendRefs: - name: guestbook port: 80httproute.yaml로 되돌려 apply 하세요.- Pod 하나의 라벨을
app=debug로 바꾼 뒤(7주차 실습 3) EndpointSlice 를 다시 보세요. 그 Pod 가 Service 목록에서도 빠졌나요? 확인 후 그 Pod 는 지우세요.
방명록의 DB 주소와 비밀번호를 ConfigMap / Secret 으로 넘기고, PostgreSQL 데이터를 PersistentVolumeClaim 에 저장합니다. 그러면 Pod 3개가 같은 DB 를 보게 되어 실습 7의 문제가 사라집니다. 5주차 Compose 로 했던 일을 Kubernetes 로 옮기는 주차입니다.
네비게이션
| 이전 | 목록 | 다음 |
|---|---|---|
| ◀ 8주차 강의 노트 | 목록으로 | 9주차 강의 노트 ▶ |